# Webhooks

Webhooks are one way disconnected web services can share data with each other, automatically. For example, say you wanted to get a user’s latest Twitter message.  Instead of constantly connecting to the twitter API every minute to check if a new message has been posted,  you can ask Twitter to update a webhook URL on each post. That means Twitter will contact you when there’s new data. But, as you can imagine, you need a webserver to listen for that posting.  In this case, Adafruit IO can act as that webhook destination.

Adafruit IO only supports receiving data at this time.

<aside class="notice">
These data publishing webhook methods <strong>do not require authentication</strong>. That
means you can freely use the URL from a public form without leaking your
authentication data.
</aside>

You can create new feed webhook receivers by visiting a feed page and using the "Webhooks" link.



## Send Data via Webhook

Create a data value. The request body should include a value parameter named either `value` or `payload` and may optionally include `lat`, `lon`, and `ele` parameters if you want to tag the data with a location.

> HTTP Request
> <div class="http"><span class="method-post">POST</span><code class="path">/api/v2/webhooks/feed/:token</code></div>

```shell
# publish as form data
curl -F "value=42" https://io.adafruit.com/api/v2/webhooks/feed/:token

# publish as JSON
curl -F '{"value":"42"}' -H 'Content-Type: application/json' \
    https://io.adafruit.com/api/v2/webhooks/feed/:token
```

```python
```

```cpp
```

```ruby
```

> Response Sample:

<%= partial 'responses/datum', locals: {value: '42'} %>



### Path Parameters

Parameter | Type    | Required  | Description
--------- | ------- | --------- | -----------------------
token     | string  | true      | the webhook token


### Body Parameters

Parameter | Type    | Required  | Description
--------- | ------- | --------- | -----------------------
value     | string  | true      | Data value
lat       | float   | false     | latitude value for location
lon       | float   | false     | longitude value for location
ele       | float   | false     | elevation value for location


## Send Arbitrary Data via Webhook

New feed data record whose value is the raw contents of the webhook request body.

Use this path if the web service you're connecting to can't be configured to match the webhook `Send Data` API body format.

> HTTP Request
> <div class="http"><span class="method-post">POST</span><code class="path">/api/v2/webhooks/feed/:token/raw</code></div>

```shell
curl -H "Content-Type: text/plain" \
    --data "this is raw data, { 'not properly formatted json' }" \
    https://io.adafruit.com/api/v2/webhooks/feed/:token/raw
```

```python
```

```cpp
```

```ruby
```

> Response Sample:

<%= partial 'responses/datum', locals: { value:  "this is raw data, { 'not properly formatted json' }"} %>


### Path Parameters

Parameter | Type    | Required  | Description
--------- | ------- | --------- | -----------------------
token     | string  | true      | the webhook token



## Send Notification via Webhook

> HTTP Request
> <div class="http"><span class="method-post">POST</span><code class="path">/api/v2/webhooks/feed/:token/notify</code></div>

```shell
$ curl -X POST https://io.adafruit.com/api/v2/webhooks/feed/:token/notify
```

```python
```

```cpp
```

```ruby
```

> Response Sample:

<%= partial 'responses/datum', locals: { value:  "ping"} %>


Creates a new feed data record with the value "ping", regardless of what was posted.

This path is helpful if you're using a low-memory MQTT client that can't handle the large webhook payloads that a service like GitHub publishes and all you care about is _that_ something happened, not _precisely what_ happened.
